1 n 1 o r - i > i c o iVi emor a n ci u m 



BCPL Users 



Data 



June 18, 1973 



Gene McDaniel. 



Location 



Subjf--.:: BCPL Machine Language Interface Organisation 



Palo Alto 
Coyote Hill 



PARC 






The follov;ing document purports to describe BCPL calling conventions 
for assembly language programmers . The following description only 
applies to pre-structure versions of BCPL. The term procedure will 
refer to both routines and procedures. 

All BCPL procedure calls use static cells which point to procedure 
code body and a few machine language routines which are always loaded 
by the BCPL loader* A procedure static cell points to the first 
executable statement in a BCPL PROCEDURE. The code in a procedure 
body references these static cells through local parameters on the 
stack or through local pointers in the code body. At the time of a 
procedure call, the stack pointer is in AC2 and the value of the 
first two parameters (if there are any) are in AC0 and AC1. 

NOTE: In the following discussion Procedure A is the 
calling procedure and Procedure B is the called 
procedure, i.e., some place "inside. A" there 
occurs the piece of code, "B (...). " 

A calls B by doing a JSR indirect through the static cell pointing to 
B. At this point, all four accumulators may have valuable data. B* s 
first action is to store AC3 (return address) in a page zero location 
and then to call "GETFRAME" through a page zero pointer (static) . 
When control returns from GETFRAME,. sundry bookkeeping information 
has been stored in the stack, all parameters, if any, have been stored 
on the stack, AC2 has the new stackpointer and hC0 , AC1, and AC3 
have been clobbered since the initial entry. 

» \ ' 

The following details about GETFRAME are of principle interest to 
the curious or to people who wish to call BCPL routines from assembly 
language programs. If you aren't interested, skip to the section on 
"How To Use It". 



GETFRAME stores the return address in B in a page zero cell- (GETFMRETURN) 
Then it stores AC0 and AC1 as the first two parameters on the new 
stack frame, along with the old (A's) stack pointer. In traditional 
NOVA custom, the word following B's'JSR to GETFRAME is a parameter - 
the size of stack frajne which B wishes allocated. BCPL will compute 
the new stack pointer and it will abort if the stack frame is too big. 
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GETFRAME also places b's return address in procedure A, the value of 
cell 203, and the number of arguments passed by A into the stack. The 
value of GETFRMRETURN plus one is assumed to be GETFRAME' s return link 
into B. That value, whose other alias is the "CODEOWNER" (i.e., of 
the current stack frame) is stored in the stack. The word immediately 
following A's original JSR to B is also treated as a parameter - the 
number of arguments which A is passing to B. If that number is two 
or fewer, GETFRAME immediately returns to B via the "CODEOWNER" entry . 
on the new stack (with the new stack pointer in AC2) . 

Procedure A places any remaining parameters in the stack in the following 
way: GETFRAME places the address minus one of where the next parameter 
should fall in the stack in cell 20B (a page zero auto incrementing cell) . 
It moves the new stack pointer into AC1, and leaves the old stack 
pointer in AC2. GETFRAME now "calls" procedure A via the return address 
in the stack. Procedure A then computes the values of the remaining 
parameters and stores them onto the new stack frame. When this process 
is complete, Procedure A calls the routine, "RECALL" through a page 
zero pointer. RECALL stores AC3 as B's correct return address into 
Procedure A onto the stack. It also assumes AC1 still contains the 
value of the new stack frame pointer which it moves into hC2 . RECALL 
then "returns" to Procedure B through the "CODEOWNER" entry on the stack. 

When procedure B wishes to return to Procedure A, it places its "RESULTIS" 
value into AC0 and calls the BCPL routine "RETURN" through a page zero 
pointer. 

RETURN performs the f ollowing operations : 

1. It returns the old value of cell 20 which was stored in 
the stack. 

2. It stores B's stackpointer into "SNEXT". 

3. It restores the old stack pointer and, finally, it 
returns control to the original caller. 



BCPL Users -3- June 18,. 1973 



The ECPL Stack 

NOTE: The stack pointer is offset by 200B to take better 
advantage of NOVA indexing hardware. 

AC2-200B+0 Old AC2 

AC2~2,00Brl Return address to caller 

AC2-200B+2 Address of code owner 

AC2-200B-i~3 Stack size = 6+ num args expected ■+ num locals 

AC2-200B+4 Old value, cell 20B 

AC2-200B+5 num args passed by caller 

AC2-200B+6 parameter 1 

AC2-200B+7 parameter 2 

How to Use It, or, Folklore Made Simple 

I. In your assembly language routines 

1. Leave a pointer to the first executable statement of each 
assembly language routine in some know n location. This 
will be your analogue of the BGPL procedure static call. 

2. Use the code shown in the example to call setframe. 

3. When done, place the result, if any, in AC0 and return to 
the BCPL calling routine as illustrated in the example. 

4. ASM your program (s) as you normally would. 

5. RLDR your programs as you normally would. Note: Do not 
put a starting address on your assembly language routines; 
this would confuse BCPL's loader. 

II. Using BCPL 

1. Compile your programs as always. 

2. See the example for how to call the assembly language procedure. 

3. Use the BCPL loader, BLDR to make the final BCPL program: 
BLDR/T/R "your assembly language save file" "/I your BCPL routines" 
If you use the DOS debugger with your assembly language 

routines, donV_t use the "/D" switch on BLDR as the loader 
(RLDR) has already placed the debugger in the assembly language 
save file. 
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If you use the, DOS debugger with your assembly language routines, don't 
use the "/D" switch on BLDR as the loader (RLDR) has already placed the 
debugger in the assembly language save file. 



Examples: in DCPL 

Let Prog = #101000// this creates a pointer to the "Assembly Language 
// Static Cell" which is presumably located location 1000B. 



FOO = PROG (A,B,C, . . .)//call the routine 
(asm. lang. examples to be provided.) 



GMcD : tn 



NOTE: Lines typed by user are underlined 



ASM/L ORIGINAL. WS^ 
Programs relocatable 

.TITL- DISK 

RLDR ORIGINAL ?- 

Disk 

No starting address for load module 

NMAX 001036 
ZMAX 000050 
CSZE 

EST 

SST 



R 

BLDR/T /R ORIGINAL/I BCPLPROG .lj> 

R 



Suppose your BCPL program is on the file, "BCPLPRCG1". In that program, 
the follov/ing sequences of code will call the assembly language program 
described above. 



LET ASMPROG = #101000 //LOCATION 1000B BETTER HAVE A POINTER TO THE SUBROUTINE 



ASMPROG (BUFFER, DISKADDR, DISKCHANNEL, READ) //CALL THE ASSEMBLY LANGUAGE 
//PROGRAM 



(VJasn't that easy!) 
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PAGE 



0001 DICK 

17 7600 



. TITL 

FIRST 
SECND 



THE STACK 

17 7607 

E FOR BCPL'S 

17 7610 THIRD 

17 7611 FORTH 

17 7012 FIFTH 

177615 SIXTH 

054 33 7 .DUSR 

TO CALL THE GUTS OF BCPL 

06 3 52 .DUSR 

ETURN, "FIXUP" CALLS 

006351 .DUSR 

RN" DOES BCPL RETURNS 

. NREL 



DISK 

-172 

-171 

-170 
-167 
-166 
-165 

SAVER 

FIXUP 
RTURN 



; DEFINE INDEX OF THE PARAMETERS ON 
; REMEMBER THAT "EARLIER" ENTRIES AR 
J INTERNAL USE. 



ST A 3, 337 
JSR 2352 
JSR 8351 



; DEFINE SOME MACROS 
; "SAVER" SAVES THE R 
;"GETFRAME" AND "RTU 



; PAG I 

00 000' 000001 'DPTR: 
PROGRAM, WE KNOW 

00001 '05133 7' DSKIO: 
OB (ABSOLUTE) 

; THE 



NG(CORE, DISK, CHANNEL, R/W FLAG) 
. +l". ; BECAUSE THIS IS THE ONLY ASSEMBLY LANGUAGE 
SAVER ;KNOW THAT "DPTR" WILL BE LOCATED AT LOG 100 

EXAMPLE BCPL PROGRAM USES THIS FACT 



00002' 
NUMBER OF 
00003' 
00004' 
00005' 
00006' 
00007' 
00010' 
00011' 
00012' 
00013* 
00014' 
00015' 
0001.6' 
00017' 
00020' 
00021' 
00022' 
00023' 
OESN'T EX 



0063 52 

PARAMETERS 
1 2 
504 26 
020424 
04 04 2 5 
021206 
025207 ■ 
3 5 211 
051210 
175004 
00 0410 
3 4 412 
054 402 
6 2 
7 0077 
4 1 3 
03 0410 
063 51 
PECT 



DISK: 
FNC: 



00024' 034404 DSKWR: 
00025' 05.1773 
00026' 000771 



00027' 076077 
00030' 07 74 77 
0031' 000010 
00032' 000000 
00033 '000000 



WREAD: 

WRITE: 

C8:- 

STACK: 

TEMP: 



FIXUP 

12 

STA 

LDA 

STA 

LDA 

LDA . 

LDA 

LDA 

MOV 

JMP 

LDA 

STA 

. SYSTM 

.RDR 

JMP 

LDA 

RTURN 



2, STACK 
0,C8 

0, TEMP 

0, FIRST, 2 

1, SECND, 2 

3, FORTH, 2 

2, THIRD, 2 

3, 3,SZR 
DSKWR 

3, WREAD 
3, FNC 

CPU 
DERRO 
2, STACK 



;CALL "GETFRAME". ADD 6 TO EXPECTED 
;4 PARAMETERS 



, SAVE STACK POINTER 
;LOOP COUNTER 

;CORE ADDRESS 
;DISK ADDRESS 
;R/W FLAG 
; CHANNEL NUMBER 
;READ ISO 
; WRITE IS 1 



; ERROR RETURN 

; RESTORE. STACK POINTER 



;DO A BCPL RETURN. CALLING PROGRAM D 
A RETURN VALUE, SO DON'T LOAD ACO. 



LDA 
STA 
JMP 

.RDR 
. WRR 
10 





00034' 030776 DERRO: LDA 



3, WRITE 
3, FNC 
DISK 

CPU 
CPU 



2, STACK 
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00035' 006351 



RTURN 
. END 



; RETURN AFTER DEBUGGING 



